<HTML>
<HEAD>
<TITLE>[Chapter 7] 7.3 BorderLayout</TITLE>
<META NAME="author" CONTENT="John Zukowski">
<META NAME="date" CONTENT="Thu Jul 31 14:39:22 1997">
<META NAME="form" CONTENT="html">
<META NAME="metadata" CONTENT="dublincore.0.1">
<META NAME="objecttype" CONTENT="book part">
<META NAME="otheragent" CONTENT="gmat dbtohtml">
<META NAME="publisher" CONTENT="O'Reilly &amp; Associates, Inc.">
<META NAME="source" CONTENT="SGML">
<META NAME="subject" CONTENT="Java AWT">
<META NAME="title" CONTENT="Java AWT">
<META HTTP-EQUIV="Content-Script-Type" CONTENT="text/javascript">
</HEAD>
<body vlink="#551a8b" alink="#ff0000" text="#000000" bgcolor="#FFFFFF" link="#0000ee">

<DIV CLASS=htmlnav>
<H1><a href='index.htm'><IMG SRC="gifs/smbanner.gif"
     ALT="Java AWT" border=0></a></H1>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch07_02.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><B><FONT FACE="ARIEL,HELVETICA,HELV,SANSERIF" SIZE="-1">Chapter 7<br>Layouts</FONT></B></TD>
<td width=172 align=right valign=top><A HREF="ch07_04.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
</table>

&nbsp;
<hr align=left width=515>
</DIV>
<DIV CLASS=sect1>
<h2 CLASS=sect1><A CLASS="TITLE" NAME="JAWT-CH-7-SECT-3">7.3 BorderLayout</A></h2>

<P CLASS=para>
<A NAME="CH07.BORDER1"></A><A NAME="CH07.BORDER2"></A><A NAME="CH07.BORDER3"></A><tt CLASS=literal>BorderLayout</tt> is the default 
<tt CLASS=literal>LayoutManager</tt> for a <tt CLASS=literal>Window</tt>. 
It provides a very flexible way of positioning components along the edges 
of the window. The following call to <tt CLASS=literal>setLayout()</tt> 
changes the <tt CLASS=literal>LayoutManager</tt> of 
the current container to the default <tt CLASS=literal>BorderLayout</tt>: 
<tt CLASS=literal>setLayout(new BorderLayout()</tt>). <A HREF="ch07_03.htm#JAWT-CH-7-FIG-4">Figure 7.4</A> 
shows a typical <tt CLASS=literal>BorderLayout</tt>. 

<DIV CLASS=figure>
<h4 CLASS=figure><A CLASS="TITLE" NAME="JAWT-CH-7-FIG-4">Figure 7.4: BorderLayout</A></h4>


<p>
<img align=middle src="./figs/jawt0704.gif" alt="[Graphic: Figure 7-4]" width=193 height=248 border=0>

</DIV>

<P CLASS=para>
<tt CLASS=literal>BorderLayout</tt> is the only layout 
provided that requires you to name components when you add them to the 
layout; if you're using a <tt CLASS=literal>BorderLayout</tt>, 
you must use <tt CLASS=literal>add(String name, Component component)</tt> 
in Java 1.0 or <tt CLASS=literal>add(Component component, String name)</tt> 
in Java 1.1 (parameter order switched). (The <tt CLASS=literal>CardLayout</tt> 
can use these versions of <tt CLASS=literal>add()</tt>, 
but does not require it.) The <tt CLASS=literal>name</tt> 
parameter of <tt CLASS=literal>add()</tt> specifies 
the region to which the component should be added. The five different regions 
are "North", "South", "East", and "West" 
for the edges of the window, and "Center" for any remaining 
interior space. These names are case sensitive. It is not necessary that 
a container use all five regions. If a region is not used, it relinquishes 
its space to the regions around it. If you <tt CLASS=literal>add()</tt> 
multiple objects to a single region, the layout manager only displays the 
last one. If you want to display multiple objects within a region, group 
them within a <tt CLASS=literal>Panel</tt> first, 
then <tt CLASS=literal>add()</tt> the <tt CLASS=literal>Panel</tt>. 

<DIV CLASS=note>
<P CLASS=note><BLOCKQUOTE><P><B>NOTE:</B> 
</blockquote><P>
</DIV>

<P CLASS=para>
In Java 1.1, if you do not provide a name, the component is placed in the "Center" 
region. 
</blockquote><P>
</DIV>

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JAWT-CH-7-SECT-3.1">BorderLayout Methods</A></h3>Constants

<P CLASS=para>
Prior to Java 1.1, you had to use string constants to specify the constraints 
when adding a component to a container whose layout is <tt CLASS=literal>BorderLayout</tt>. 
With Java 1.1, you can use class constants, instead of a literal string, in the following list. 

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public static final String CENTER <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>CENTER</tt> constant represents 
the "Center" string and indicates that a component should be 
added to the center region. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public static final String EAST <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>EAST</tt> constant represents 
the "East" string and indicates that a component should be 
added to the east region. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public static final String NORTH <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>NORTH</tt> constant represents 
the "North" string and indicates that a component should be 
added to the north region. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public static final String SOUTH <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>SOUTH</tt> constant represents 
the "South" string and indicates that a component should be 
added to the south region. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public static final String WEST <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>WEST</tt> constant represents 
the "West" string and indicates that a component should be 
added to the west region. </DL>
Constructors

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public BorderLayout () </I><br>
<DD>

<P CLASS=para>
This constructor creates a <tt CLASS=literal>BorderLayout</tt> 
using a default setting of zero pixels for the horizontal and vertical 
gaps. The gap specifies the space between adjacent components. With horizontal 
and vertical gaps of zero, components in adjacent regions will touch each 
other. As <A HREF="ch07_03.htm#JAWT-CH-7-FIG-4">Figure 7.4</A> shows, each component within 
a <tt CLASS=literal>BorderLayout</tt> will be resized 
to fill an entire region. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public BorderLayout (int hgap, int vgap) </I><br>
<DD>

<P CLASS=para>
This version of the constructor allows you to create a <tt CLASS=literal>BorderLayout</tt> 
with a horizontal gap of <tt CLASS=literal>hgap</tt> 
and vertical gap of <tt CLASS=literal>vgap</tt>, putting 
some space between the different components. The units for gaps are pixels. 
It is possible to have negative gaps if you want components to overlap. </DL>
Informational methods

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public int getHgap () <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getHgap()</tt> method retrieves 
the current horizontal gap setting. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void setHgap (int hgap) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>setHgap()</tt> method changes 
the current horizontal gap setting to <tt CLASS=literal>hgap</tt>. 
After changing the gaps, you must <tt CLASS=literal>validate()</tt> 
the <tt CLASS=literal>Container</tt>. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public int getVgap () <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getVgap()</tt> method retrieves 
the current vertical gap setting. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void setVgap (int hgap) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>setVgap()</tt> method changes 
the current vertical gap setting to <tt CLASS=literal>vgap</tt>. 
After changing the gaps, you must <tt CLASS=literal>validate()</tt> 
the <tt CLASS=literal>Container</tt>. </DL>
LayoutManager methods

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public void addLayoutComponent (String name, Component component) <img src="gifs/wstar.gif" alt="(Deprecated)" border=0> </I><br>
<DD>

<P CLASS=para>
This version of <tt CLASS=literal>addLayoutComponent()</tt> 
has been deprecated and replaced by the <tt CLASS=literal>addLayoutComponent(Component, 
Object)</tt> method of the <tt CLASS=literal>LayoutManager2</tt> 
interface. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void removeLayoutComponent (Component component)  </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>removeLayoutComponent()</tt> 
method of <tt CLASS=literal>BorderLayout</tt> removes 
<tt CLASS=literal>component</tt> from the container, 
if it is in one of the five regions. If <tt CLASS=literal>component</tt> 
is not in the container already, nothing happens. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public Dimension preferredLayoutSize (Container target)  </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>preferredLayoutSize()</tt> method 
of <tt CLASS=literal>BorderLayout</tt> calculates 
the preferred dimensions for the components in <tt CLASS=literal>target</tt>. 
To compute the preferred height, a <tt CLASS=literal>BorderLayout</tt> 
adds the height of the <tt CLASS=literal>getPreferredSize()</tt> 
of the north and south components to the maximum <tt CLASS=literal>getPreferredSize()</tt> 
height of the east, west, and center components. The vertical gaps are 
added in for the north and south components, if present. The top and bottom 
insets are also added into the height. To compute the preferred width, 
a <tt CLASS=literal>BorderLayout</tt> adds the width 
of the <tt CLASS=literal>getPreferredSize()</tt> of 
east, west, and center components, along with the horizontal gap for the 
east and west regions. It compares this value to the preferred widths of 
the north and south components. The <tt CLASS=literal>BorderLayout</tt> 
takes the maximum of these three and then adds the left and right insets, 
plus twice the horizontal gap. The result is the preferred width for the 
container. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public Dimension minimumLayoutSize (Container target)  </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>minimumLayoutSize()</tt> method 
of <tt CLASS=literal>BorderLayout</tt> calculates 
the minimum dimensions for the components in <tt CLASS=literal>target</tt>. 
To compute the minimum height, a <tt CLASS=literal>BorderLayout</tt> 
adds the height of the <tt CLASS=literal>getMinimumSize()</tt> 
of the north and south components to the maximum of the minimum heights 
of the east, west, and center components. The vertical gaps are added in 
for the north and south components, if present, along with the container's 
top and bottom insets. To compute the minimum width, a <tt CLASS=literal>BorderLayout</tt> 
adds the width of the <tt CLASS=literal>getMinimumSize()</tt> 
of east, west, and center components, along with the horizontal gap for 
the east and west regions. The <tt CLASS=literal>BorderLayout</tt> 
takes the maximum of these three and then adds the left and right insets, 
plus twice the horizontal gap. The result is the minimum width for the 
container. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public void layoutContainer (Container target)  </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>layoutContainer()</tt> method 
draws <tt CLASS=literal>target</tt>'s components 
on the screen in the appropriate regions. The north region takes up the 
entire width of the container along the top. South does the same along 
the bottom. The heights of north and south will be the heights of the components 
they contain. The east and west regions are given the widths of the components 
they contain. For height, east and west are given whatever is left in the 
container after satisfying north's and south's height requirements. 
If there is any extra vertical space, the east and west components are 
resized accordingly. Any space left in the middle of the screen is assigned 
to the center region. If there is insufficient space for all the components, 
space is allocated according to the following priority: north, south, west, 
east, and center. Unlike <tt CLASS=literal>FlowLayout</tt>, 
<tt CLASS=literal>BorderLayout</tt> reshapes the internal 
components of the container to fit within their region. <A HREF="ch07_03.htm#JAWT-CH-7-FIG-5">Figure 7.5</A> 
shows what happens if the east and south regions are not present and the 
gaps are nonzero. </DL>
<DIV CLASS=figure>
<h4 CLASS=figure><A CLASS="TITLE" NAME="JAWT-CH-7-FIG-5">Figure 7.5: BorderLayout with missing regions</A></h4>


<p>
<img align=middle src="./figs/jawt0705.gif" alt="[Graphic: Figure 7-5]" width=193 height=248 border=0>

</DIV>

LayoutManager2 methods

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public void addLayoutComponent (Component component, Object name) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
This <tt CLASS=literal>addLayoutComponent()</tt> method 
puts <tt CLASS=literal>component</tt> in the <tt CLASS=literal>name</tt> 
region of the container. In Java 1.1, if <tt CLASS=literal>name</tt> 
is null, <tt CLASS=literal>component</tt> is added 
to the center. If the name is not "North", "South", 
"East", "West", or "Center", the component 
is added to the container but won't be displayed. Otherwise, it 
is displayed in the appropriate region. 

<P CLASS=para>
There can only be one component in any region, so any component already 
in the named region is removed. To get multiple components in one region 
of a <tt CLASS=literal>BorderLayout</tt>, group the 
components in another container, and add the container as a whole to the 
layout. 

<P CLASS=para>
If <tt CLASS=literal>name</tt> is not a <tt CLASS=literal>String</tt>, 
<tt CLASS=literal>addLayoutComponent()</tt> throws 
the run-time exception <tt CLASS=literal>IllegalArgumentException</tt>. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public abstract Dimension maximumLayoutSize(Container target) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>maximumLayoutSize()</tt> method 
returns a <tt CLASS=literal>Dimension</tt> object 
with a width and height of <tt CLASS=literal>Integer.MAX_VALUE</tt>. 
In effect, this means that <tt CLASS=literal>BorderLayout</tt> 
does not support the concept of maximum size. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public abstract float getLayoutAlignmentX(Container target) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getLayoutAlignmentX()</tt> method 
says that <tt CLASS=literal>BorderLayout</tt> containers 
should be centered horizontally within the area available. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public abstract float getLayoutAlignmentY(Container target) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>getLayoutAlignmentY()</tt> method 
says that <tt CLASS=literal>BorderLayout</tt> containers 
should centered vertically within the area available. 

<p>
<DT CLASS=varlistentry><I CLASS=emphasis>public abstract void invalidateLayout(Container target) <img src="gifs/bstar.gif" alt="(New)" border=0> </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>invalidateLayout()</tt> method 
of <tt CLASS=literal>BorderLayout</tt> does nothing. </DL>
Miscellaneous methods

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><I CLASS=emphasis>public String toString () </I><br>
<DD>

<P CLASS=para>
The <tt CLASS=literal>toString()</tt> method of <tt CLASS=literal>BorderLayout</tt> 
returns a string showing the current horizontal and vertical gap settings. 
If both gaps are zero, the result will be: </DL>
<DIV CLASS=screen>
<P>
<PRE>
java.awt.BorderLayout[hgap=0,vgap=0]
</PRE>
</DIV>

</DIV>

</DIV>


<DIV CLASS=htmlnav>

<P>
<HR align=left width=515>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch07_02.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><a href="index.htm"><img src='gifs/txthome.gif' border=0 alt='Home'></a></td>
<td width=172 align=right valign=top><A HREF="ch07_04.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
<tr>
<td width=172 align=left valign=top>FlowLayout</td>
<td width=171 align=center valign=top><a href="index/idx_a.htm"><img src='gifs/index.gif' alt='Book Index' border=0></a></td>
<td width=172 align=right valign=top>GridLayout</td>
</tr>
</table>
<hr align=left width=515>

<IMG SRC="gifs/smnavbar.gif" USEMAP="#map" BORDER=0> 
<MAP NAME="map"> 
<AREA SHAPE=RECT COORDS="0,0,108,15" HREF="../javanut/index.htm"
alt="Java in a Nutshell"> 
<AREA SHAPE=RECT COORDS="109,0,200,15" HREF="../langref/index.htm" 
alt="Java Language Reference"> 
<AREA SHAPE=RECT COORDS="203,0,290,15" HREF="../awt/index.htm" 
alt="Java AWT"> 
<AREA SHAPE=RECT COORDS="291,0,419,15" HREF="../fclass/index.htm" 
alt="Java Fundamental Classes"> 
<AREA SHAPE=RECT COORDS="421,0,514,15" HREF="../exp/index.htm" 
alt="Exploring Java"> 
</MAP>
</DIV>

</BODY>
</HTML>
